voluModel: Modelling species distributions in three‐dimensional space

Ecological niche modelling and species distribution techniques (ENM SDM respectively) were first developed to infer putative suitable environmental conditions for in terrestrial systems. While there are distinctions be made between ENM SDM, hereafter we primarily use the term ‘ENM’, as SDMs can considered ENMs that have subsequently been projected into geographic space (Warren, 2012). workflows stand-alone programmes generally accept a set of points, expressed latitudinal longitudinal coordinates, representing where interest has observed (i.e. presences or occurrences). Depending on algorithm, coordinate datasets may also include points species' absences, pseudoabsences background data full range environments accessible (Barve et al., 2011; Elith 2011). In some workflows, accompany these data; others, (e.g. temperature, precipitation, salinity, etc.) extracted at occurrence from 2-D layers conditions. Once an is calibrated, it then used model potential geographical by projecting modelled using raster within area interest. Critically marine species, two-dimensionally summarized coordinates provide inaccurate estimate abiotic ecological observed, change strikingly with depth (Figure 1; Duffy & Chown, 2017). One early approach explicitly incorporating depth-structured pelagic combined all vertical dataset side continuous grid projection (Bentlage 2013); another trained based directly pseudoabsence results onto each layer (Duffy However, neither methods widely adopted modellers. This partly due lack tools—both studies supply bespoke scripts repeat analyses they present, but do not easily generalizable scalable would facilitate more widespread methodological adoption. There remains need tools efficiently niches distributions three dimensions (Melo-Merino 2020). Here, present voluModel, R (R Core Team, 2021) package simple, repeatable 3-D workflows. We designed voluModel aid processing inputs outputs (Table 1), while allowing user maximum flexibility study design algorithm choice. The process starts downsampling point voxel (3-D pixel equivalent) resolution represented RasterBrick multilayer) object. provides interpolate smooth unevenly sampled cases expected spatially autocorrelated. If appropriate user's choice, next delimits training region draws background, absence region. Next, facilitates extraction latitude longitude) depth) occurrence, optionally, true points. generate models established algorithms points-with-data perform projections programmatically simple scripted loops. Finally, allows visualize assess extrapolation risk 3-D. section 4, example generalized linear workflow; envelope workflow found ‘Introduction voluModel’ vignette (https://cran.r-project.org/web/packages/voluModel/vignettes/a_Introduction.html). A key interface horizontal data. xyzSample() extracts presences, absences points). To reduce biasing inference pseudoreplicated presence (Aiello-Lammens 2015), downsample() reduces sampling dataset; context, loops across template template's resolution. That is, if than one falls given voxel, aggregated replaced single centre voxel. compared original pointCompMap(), plotting function wrapper around ggplot() (ggplot2; Wickham, 2016) comparing positions two datasets. For dataset, pointMap(), wrapper, generates formatted map positions. sample and/or important consider 2011) which referred literature M, among others. Generally, users should carefully curate backgrounds reflect biological realities regions being sampled. absent specific information dispersal capabilities, algorithmically generating clear rules suitable. marineBackground() getDynamicAlphaHull() rangeBuilder (Rabosky 2016); fitting alpha hull polygon dataset. extends functionality address issues polygons ways: clip only oceans, deleting unoccupied after clipping 2a), wrapping antemeridian 180°E W) instead truncating them. generated, saved shapefiles edited hand GIS program desired. downsampled defined extract input mSampling3D() data.frame overlapping generated marineBackground()). Either depths limit minimum manually specify sampling. mSampling2D() performs analogous actions limited layer. several encountered commonly variables dissolved oxygen) shapefiles, such World Ocean Atlas (Garcia 2018). First, variable shapefile read SpatialPointsDataFrame object; row column position water column. WOA oxygen, Garcia 2019), measurements uniformly distributed space; missing inferred thin plate spline (Boer 2001) interpolateRaster() function. smoothRaster() uses spline, adjusts noisy assumption spatial correlation (Hutchinson, 1995). Both smoothRaster()use TPS() fields (Nychka 2015) accommodate large fastTPS() approximation, fields. assist previously implemented techniques, bottomRaster() deepest measurement cell SpatialPointsDataFrame. benthic bottom rasters those data, treat care. particular always ocean (Sayre spplot() sp (Pebesma Bivand, 2005) maps optional land context. rasterComp() plots semitransparent binary presence/absence) show overlaps, wish compare 2b). plotLayers() takes presence/absence brick overlay, colour-coded relatively 2c). resulting plot, pinker hues shallower bluer deeper saturated colours indicate wider depths. oneRasterPlot() single, high-contrast, colour-blind-friendly palettes viridis (Garnier 2021). When space, novel necessary (Elith 2010). necessarily unwarranted make realistic predictions, this case (Owens 2013). Several metrics proposed extrapolation, far most common Multivariate Environmental Similarity Surface (MESS; MESS compares values reference (typically train model), returning negative dissimilar set. implementation mess() dismo (Hijmans 2021), called MESS3D(). MESS3D() point-associated named list objects containing produces scores. Areas highest visualized reclassifying 1, positive 0, mapping plotlayers(). high estimated removed math (see ‘3-D Niche Modelling GLM Algorithm’ vignette: https://cran.r-project.org/web/packages/voluModel/vignettes/e_GLMWorkflow.html). illustrate tools, potentially habitat Luminous Hake, Steindachneria argentea. Hake gadiform codfish Gulf Mexico Caribbean Sea (Cohen 1990) diurnal migrant. Daytime surveys recorded Hakes ~200 ~1300 m (Benavides-Morera Campos-Calderón, 2018); nighttime ~30 ~190 (Love 2004). downloaded via OBIS (obis.org, 24 September 2020 robis, Provoost Bosch, 2019) GBIF (gbif.org, rGBIF, Chamberlain occCite Full citations natural history collections contributing (https://cran.r-project.org/web/packages/voluModel/vignettes/e_GLMWorkflow.html). 2018): mean annual temperature (Locarnini 2018) apparent oxygen utilization (AOU; 2019). chose their relevance selection simplicity example. real-world analyses, recommend exploring additional explanatory available other similar sources. packaged voluModel. demonstrates code estimates Hake. includes removal areas results; surface 2b) Overall, surface-based identified extensive bottom-based model. extremes open Sea. development ongoing; dependent functions, object classes (Hijmans, 2022a) rgeos (Bivand Rundel, will soon retired performance-optimized packages, updated equivalent elements sf (Pebesma, 2018), terra 2022b) stars 2022). Future versions functions Maxent; Phillips 2017), estimating measures Most Dissimilar Variable, 2010; Extrapolation Detection, Mesgaran 2014; Movement-Oriented Parity, Owens 2013) features requested users. innovations allow researchers fine-grained, accurately, addressing long-standing studies. Our method forest canopy- soil-dwelling organisms, obtainable. From modern biodiversity perspective, stacking our yield precise open-ocean richness insights how varies depth. Projecting through time accurate shifted both past, well predicting shift future. improved suitability predictions contribute substantially towards data-driven conservation efforts, including sustainable management plans robust protected design. Hannah L. Carsten Rahbek conceived idea methodology; analysed led writing manuscript. authors contributed critically final version manuscript, gave approval publication. project received funding European Union's Horizon research innovation programme under Marie Skłodowska-Curie grant agreement No 891702. CR was further supported no. 25925 VILLUM FONDEN. any conflicts peer review article https://www.webofscience.com/api/gateway/wos/peer-review/10.1111/2041-210X.14064. CRAN: https://CRAN.R-project.org/package=voluModel; accessed https://github.com/hannahlowens/voluModel. manuscript (v1.8; Rahbek, 2022) cited DOI: http://doi.org/10.5281/zenodo.7372599. Data S1: Supporting information. Please note: publisher responsible content supporting supplied authors. Any queries (other content) directed corresponding author article.